C.S.Burner 🪙 ━►🔥GIT Node

Micron Document

Node / reticulum_mirror / MeshChatX / files / docs / en / rns-link-api.md

Displaying Rendered • View raw • Download

docs/en/rns-link-api.md dev (54b0734e) Text, 7.04 KB

RNS Link API

MeshChatX exposes a generic Reticulum Link transport on the main WebSocket (T383838/ws). External apps and plugins can open links, run request/response exchanges, send packets, and tear links down without going through NomadNet helpers.

When to use it

T282828

Your app or plugin needs a live RNS Link

--> Not NomadNet page browsing

--> Not LXMF messaging

--> Use rns.link.* over /ws

or plugin managers rnsLink.*

Address peers by destination hash and aspect. Do not invent IP or hostname shortcuts.

Auth

When password auth is enabled, every T383838rns.link.* client message needs an authenticated session. Same rule as other WebSocket mutators.

Link lifecycle

T282828

Client sends rns.link.open

--> MeshChatX finds or opens path to destination

--> Link cached under (aspect, destination_hash)

--> Optional auto_identify

--> success / failure reply on same type + request_id

+--> rns.link.request / rns.link.send on the cached link

+--> rns.link.close tears down and uncaches

+--> disconnect cancels in-flight open / request for that client

Cache notes:

• Key is T383838(aspect, destination_hash)

• Cap is 64 active links

• Idle links expire after about 30 minutes

• Repeated request failures recycle the cached link so the next call re-opens

Client to server

All messages need a unique T383838request_id so replies can be matched.

┌───────────────────┬───────────────────────────────────────────────────┬───────────────────┬──────┐

│ `BT383838`Fdddtype`f`b │ Required fields │ Optional │ Beh… │

├───────────────────┼───────────────────────────────────────────────────┼───────────────────┼──────┤

│ T383838rns.link.open │ T383838destination_hash, T383838aspect, T383838request_id │ T383838auto_identify │ Ope… │

│ T383838rns.link.identify │ T383838destination_hash, T383838aspect, T383838request_id │ │ Cal… │

│ T383838rns.link.request │ T383838destination_hash, T383838aspect, T383838path, T383838request_id │ T383838data_b64, T383838timeout │ Ens… │

│ T383838rns.link.send │ T383838destination_hash, T383838aspect, T383838payload_b64, T383838request_id │ │ Sen… │

│ T383838rns.link.close │ T383838destination_hash, T383838aspect, T383838request_id │ │ Tea… │

└───────────────────┴───────────────────────────────────────────────────┴───────────────────┴──────┘

Field details:

• T383838destination_hash: hex string of the peer destination

• T383838aspect: dot-separated RNS app name + sub-aspects, for example T383838microrn.mgmt

• T383838data_b64 / T383838payload_b64 / reply T383838body_b64: msgpack payloads, base64-encoded

• T383838path: request path string on the remote link endpoint

• T383838timeout: seconds for the request wait

Example open:

T282828

Tb4b4b4{

Tff7b72"type"Tb4b4b4: Ta5d6ff"rns.link.open"Tb4b4b4,

Tff7b72"destination_hash"Tb4b4b4: Ta5d6ff"aabbccddeeff00112233445566778899aabbccdd"Tb4b4b4,

Tff7b72"aspect"Tb4b4b4: Ta5d6ff"microrn.mgmt"Tb4b4b4,

Tff7b72"request_id"Tb4b4b4: Ta5d6ff"req-1"Tb4b4b4,

Tff7b72"auto_identify"Tb4b4b4: Tff7b72true

Tb4b4b4}

Example request:

T282828

Tb4b4b4{

Tff7b72"type"Tb4b4b4: Ta5d6ff"rns.link.request"Tb4b4b4,

Tff7b72"destination_hash"Tb4b4b4: Ta5d6ff"aabbccddeeff00112233445566778899aabbccdd"Tb4b4b4,

Tff7b72"aspect"Tb4b4b4: Ta5d6ff"microrn.mgmt"Tb4b4b4,

Tff7b72"path"Tb4b4b4: Ta5d6ff"/status"Tb4b4b4,

Tff7b72"request_id"Tb4b4b4: Ta5d6ff"req-2"Tb4b4b4,

Tff7b72"data_b64"Tb4b4b4: Tff7b72nullTb4b4b4,

Tff7b72"timeout"Tb4b4b4: T79c0ff15

Tb4b4b4}

Server to client

Per-T383838request_id replies reuse the same T383838type with a T383838status:

┌──────────┬──────────────────────────────────────────────┐

│ `BT383838`Fdddstatus`f`b │ Meaning │

├──────────┼──────────────────────────────────────────────┤

│ T383838phase │ Progress step while opening or requesting │

│ T383838progress │ Additional progress detail when available │

│ T383838success │ Operation finished │

│ T383838failure │ Operation failed (includes an error message) │

└──────────┴──────────────────────────────────────────────┘

Broadcast events (not tied to one T383838request_id):

┌────────────────┬─────────────────┬──────────────────────┐

│ `BT383838`Fdddtype`f`b │ `BT383838`Fdddevent`f`b │ Notes │

├────────────────┼─────────────────┼──────────────────────┤

│ T383838rns.link.event │ T383838packet_received │ Includes T383838payload_b64 │

│ T383838rns.link.event │ T383838link_closed │ Cached link removed │

└────────────────┴─────────────────┴──────────────────────┘

T282828

Inbound packet on a cached link

--> Broadcast rns.link.event / packet_received

Link torn down or evicted

--> Broadcast rns.link.event / link_closed

Plugins

Plugins call the same transport through HTTP invoke instead of speaking WebSocket types directly.

T282828

Plugin Worker

--> POST /api/v1/plugins/{id}/invoke

method: "callManager"

--> PluginManager checks granted managers

--> RnsLinkManager open / identify / request / send / close

Declare managers in T383838plugin.json:

┌──────────────────┬─────────────────────────┐

│ Manager │ Maps to │

├──────────────────┼─────────────────────────┤

│ T383838rnsLink.open │ Open or reuse link │

│ T383838rnsLink.identify │ Identify on cached link │

│ T383838rnsLink.request │ Request/response │

│ T383838rnsLink.send │ Raw packet send │

│ T383838rnsLink.close │ Teardown │

└──────────────────┴─────────────────────────┘

Subscribe to async traffic with:

T282828

Tb4b4b4{

Tff7b72"permissions"Tb4b4b4: Tb4b4b4{

Tff7b72"hooks"Tb4b4b4: Tb4b4b4[Ta5d6ff"rns.link.event"Tb4b4b4],

Tff7b72"managers"Tb4b4b4: Tb4b4b4[Ta5d6ff"rnsLink.open"Tb4b4b4, Ta5d6ff"rnsLink.identify"Tb4b4b4, Ta5d6ff"rnsLink.request"Tb4b4b4, Ta5d6ff"rnsLink.send"Tb4b4b4, Ta5d6ff"rnsLink.close"Tb4b4b4],

Tff7b72"storage"Tb4b4b4: Ta5d6ff"isolated"Tb4b4b4,

Tff7b72"network"Tb4b4b4: Ta5d6ff"none"

Tb4b4b4}

Hook delivery:

T282828

RnsLinkManager event

--> PluginManager.dispatch_hook("rns.link.event", …)

--> WebSocket plugin.event to the UI

--> Plugin Worker on_hook / event handler

External app pattern

T282828

Connect to MeshChatX /ws (auth cookie / session as required)

--> Send rns.link.open with request_id

--> Wait for matching success

--> Send rns.link.request or rns.link.send

--> Listen for rns.link.event broadcasts

--> Send rns.link.close when finished

Keep one T383838request_id per outstanding call. Cancel or ignore replies after you disconnect. MeshChatX cancels in-flight open/request work for that WebSocket client on disconnect.

Limits and failure behaviour

• Missing path or unreachable peer returns T383838failure on the open/request reply

• After repeated request failures on one cached link, MeshChatX recycles that link

• Idle unused links are swept after about 30 minutes

• Over-cap eviction drops the oldest unused links first

Implementation map

T282828

/ws rns.link.*

--> meshchat.py WebSocket dispatch + per-client task tracking

--> rns_link_manager.py cache, open, identify, request, send, close

--> plugin_manager.py capability wrappers + hook fan-out